home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 401-425 / disk_403 / rexxhostlib / rexxhost.doc < prev    next >
Text File  |  1992-05-06  |  20KB  |  460 lines
  1. ====================== RexxHost.Library v36.14 =======================
  2. ======================================================================
  3. An Amiga shared library for creating/managing ARexx host environments.
  4. ======================================================================
  5.  
  6. ========================== IMPORTANT NOTICE ==========================
  7. ======================================================================
  8. This is the official new release of rexxhost.library.  Due to register
  9. rearrangements  programs compiled using the old 1.6 release have to be
  10. recompiled  or  serious  system  crashes  will  result!  Note that the
  11. supplied library code can only be recompiled under Aztec 'C' 5.0.
  12.  
  13. ============================= Background =============================
  14. ======================================================================
  15. A  friend  of mine was busy developing a stock management program when
  16. he suddenly realized that an ARexx interface would be the only feature
  17. that wasn't already part of his project.  So he started to analyze, to
  18. program,  to  try - just to find out that it would be too much work to
  19. add it.
  20.         Some  months later a programmer who works for the same company
  21. I  am  working  for decided to rewrite his home-brewn assembler/linker
  22. program  to  interface to CygnusEd Professional.  The problem is:  his
  23. program  is written in assembly language, the standard host management
  24. routines are written in 'C'...
  25.         To  simplify  the host creation/management procedure I decided
  26. to  put  the  required  routines  and  some  extra  code into a shared
  27. library,  easy  to  use  by  ANY  language (can you imagine AmigaBASIC
  28. controlling AmigaTeX?).
  29.         As  soon  as the Aztec 'C' 5.0 update came in, the library has
  30. been  updated  to  take  advantage  of  the  new compiler features.  I
  31. suppose  the  source  code  can  be  seen  as  a  real  'treasure' for
  32. programmers  who also wish to build shared libraries with the new Manx
  33. compiler but find the original Manx support code a bit too confusing.
  34.  
  35. ========================= Supplied material ==========================
  36. ======================================================================
  37.  
  38.         The RexxHostLib package contains the following files:
  39.         -----------------------------------------------------
  40.         FancyDemo.............. Demonstration program
  41.         FancyDemo.c............ Source code for demonstration program
  42.  
  43.         LibStartup.asm......... Library support code
  44.  
  45.         LibMain.c.............. Library support code
  46.         PreInclude.c........... Source for precompiled header
  47.                                 file
  48.         RexxHostLib.c.......... Library support code
  49.         rexxhostbase.h......... Library header file
  50.         StringAsm.asm.......... Assembly language string routines
  51.  
  52.         rexxhostlat.lib........ Lattice 'C' linker library
  53.         rexxhostnew.lib........ Aztec 'C' 5.0 linker library
  54.         rexxhostold.lib........ Aztec 'C' 3.6 linker library
  55.  
  56.         rexxhost.library....... Amiga shared library
  57.  
  58.         MakeFile............... Library building-instructions
  59.  
  60.         rexxhost_lib.fd........ Library function definitions
  61.  
  62.         TestDemo.rexx.......... ARexx demonstration script
  63.  
  64.         RexxHost.doc........... This file
  65.  
  66.         Glue.LZH............... LhArc archive containing library
  67.                                 glue routine source codes
  68.  
  69. ============================= How to use =============================
  70. ======================================================================
  71. The  rexxhost.library needs ARexx (any version will do, v1.10 is best)
  72. to  work properly.  It needs to be opened EXPLICITELY, i.e.  it is not
  73. forced  into  memory by the ARexx server and CANNOT be loaded with the
  74. ADDLIB() call in rexx-scriptfiles.  An unlimited number of callers may
  75. open   the   library,   it   is   100%   reentrant.    Just  like  the
  76. rexxsyslib.library   the   rexxhost.library   stays  in  memory  until
  77. explicitely expunged (e.g.  via "flushlibs" call from Workbench).
  78.         The  OpenLibrary()  call  returns  a pointer to a RexxHostBase
  79. structure (as defined in the rexxhostbase.h include file).  It has the
  80. following format:
  81.  
  82.                 struct RexxHostBase
  83.                 {
  84.                         struct Library   LibNode;
  85.                         struct RxsLib   *RexxSysBase;
  86.                 };
  87.  
  88. The  pointer  to the RxsLib structure represents a pointer to the base
  89. of  rexxsyslib.library.   It  can  be  copied  by the calling process,
  90. rexxsyslib.library does not need to be opened explicitely.
  91.         All library functions are "bullet proof", i.e. if the supplied
  92. arguments  are  illegal  the  functions return immediately.  Note that
  93. this  library  only  contains  basic support functions, you will still
  94. have  to  do  command analysis, parsing and command processing on your
  95. own (which isn't difficult, look at the DClockHandler.c sourcecode for
  96. an example).
  97.  
  98. ============================= Compiling ==============================
  99. ======================================================================
  100. A  Makefile  for  Aztec  'C'  5.0 is supplied.  This version CANNOT be
  101. recompiled under compiler versions previous to 5.0.  Note that line 67
  102. in the ARexx 'C' include file 'rxslib.h' has to be changed from:
  103.  
  104.         WORD rl_NumMsg; /* pending count */
  105.  
  106. to:
  107.  
  108.         WORD rl_PgmMsg; /* pending count */
  109.  
  110. or  you  will  get  a 'multiple entry' message from the compiler (Bill
  111. obviously overlooked the misspelled entry).  In order to recompile the
  112. library the following symbol must be defined in your header files:
  113.  
  114.         #define AG_CloseLib     0x00090000
  115.  
  116. The  linker  requires  a  library  which  contains  glue codes for all
  117. rexxsyslib.library routines (rexx.lib).
  118.  
  119. ===================== RexxHost.Library Functions =====================
  120. ======================================================================
  121.  
  122. CreateRexxHost - Create a RexxHost with supplied name
  123.  
  124. Usage:
  125. RexxHost = CreateRexxHost(HostName)
  126.   D0                         A0
  127.  
  128. This  function  tries  to  allocate a public messageport with a unique
  129. name.   If  a  port  with the supplied name does already exist NULL is
  130. returned.   The  name of the HostPort to be created is copied so there
  131. is  no  need  to  keep  it  statically initialized in you application.
  132. Note:   NEVER use this function if you only want to allocate a general
  133. purpose  MsgPort.   Some  additional  type  checking  is  done in this
  134. routine.   A  RexxHost  is  an  extended  MsgPort  structure with some
  135. additional  data  which allows all library functions to test if a host
  136. address  is valid.  You should rather see a RexxHost as a MsgPort.  Do
  137. not  rely  on  the  existence  of  the  flags  following  the  MsgPort
  138. structure.
  139.  
  140.  
  141. DeleteRexxHost - Remove RexxHost
  142.  
  143. Usage:
  144. NULL = DeleteRexxHost(RexxHost)
  145.  D0              A0
  146.  
  147. A  supplied  RexxHost  is  removed  from the system, freeing allocated
  148. signals  and  nodes.  A NULL-pointer is always returned so user can do
  149. 'Host  =  DeleteRexxHost(Host);'.  Never use this function to remove a
  150. general   purpose   MsgPort  from  the  system  list,  in  which  case
  151. DeleteRexxHost()  is  guaranteed  to  return immediately without doing
  152. anything.
  153.  
  154.  
  155. SendRexxCommand() - Send a command to the rexx server
  156.  
  157. Usage:
  158. Success = SendRexxCommand(RexxHost,CommandString,FileExtension,HostName)
  159.   D0                         A0          A1             A2        A3
  160.  
  161. This  function  causes  the  rexx  server  to  execute  a script file.
  162. HostPort  must  point  to the host RexxHost, CommandString points to a
  163. string   containing   the   name   of  the  command  to  be  executed.
  164. FileExtension   and   HostName   are   optional   and   may  be  NULL.
  165. FileExtension  defines  the  script  file name extension for this host
  166. (for  standard rexx scripts this is ".rexx", for CygnusEd Professional
  167. it  is  ".ced").   HostName  is  supplied to allow the host to address
  168. different  sub-hosts, such as different windows a text editor may have
  169. open.  This function returns FALSE (= 0) if the command cannot be sent
  170. (rexx  may  not  be  running)  and  TRUE (= 1) if the message has been
  171. posted.
  172.  
  173.  
  174. FreeRexxCommand() - Free the contents of a RexxMsg
  175.  
  176. Usage:
  177. FreeRexxCommand(RexxMessage)
  178.                     A0
  179.  
  180. Having  successfully  called  SendRexxCommand()  the  rexx server will
  181. return the RexxMsg with result flags set.  This kind of message cannot
  182. be  replied (since it already has been replied by the rexx server) but
  183. has  to  be  deallocated.   Be  sure  to examine the result code flags
  184. before you remove the RexxMsg.
  185.  
  186.  
  187. ReplyRexxCommand() - Returns a RexxMsg to the rexx server
  188.  
  189. Usage:
  190. ReplyRexxCommand(RexxMessage,Primary,Secondary,Result)
  191.                      A0         D0      D1       A1
  192.  
  193. Having received a command from the rexx server the host has to process
  194. it.  After that the RexxMsg has to be replied so the rexx server knows
  195. about  the  result.  Primary and Secondary are the values to be passed
  196. in  the  result flags of the RexxMsg structure, Result is optional and
  197. may  be  NULL.   It  usually  points to a string containing the result
  198. (numeric or string) of the command having been executed.
  199.  
  200.  
  201. GetRexxCommand() - Get the first argument from a RexxMsg
  202.  
  203. Usage:
  204. String = GetRexxCommand(RexxMessage)
  205.   D0                        A0
  206.  
  207. This  function  is  supported to save the calling program from dealing
  208. with  pointer  offsets  (which  may  be  difficult  with some language
  209. implementations).  It returns a pointer to the first argument entry in
  210. the  supplied  RexxMsg  structure.   This  is  usually a command to be
  211. executed by the host.  If NULL is returned then the RexxMsg is a reply
  212. to a former SendRexxCommand() command.
  213.  
  214.  
  215. GetRexxArg() - Get the first argument from a RexxMsg
  216.  
  217. Usage:
  218. String = GetRexxArg(RexxMessage)
  219.   D0                    A0
  220.  
  221. This  function  is  supported to save the calling program from dealing
  222. with  pointer  offsets  (which  may  be  difficult  with some language
  223. implementations).  It returns a pointer to the first argument entry in
  224. the  supplied RexxMsg structure.  This function is almost identical to
  225. GetRexxCommand(),  the  string  pointer is always returned, no RexxMsg
  226. type consideration is done.
  227.  
  228.  
  229. GetRexxResult1() - Get the first RexxMsg result code
  230.  
  231. Usage:
  232. Result = GetRexxResult1(RexxMessage)
  233.   D0                        A0
  234.  
  235. This  function  is  supported to save the calling program from dealing
  236. with  pointer  offsets  (which  may  be  difficult  with some language
  237. implementations).  It returns the value of the first result code entry
  238. in the supplied RexxMsg structure.
  239.  
  240.  
  241. GetRexxResult2() - Get the second RexxMsg result code
  242.  
  243. Usage:
  244. Result = GetRexxResult2(RexxMessage)
  245.   D0                        A0
  246.  
  247. This  function  is  supported to save the calling program from dealing
  248. with  pointer  offsets  (which  may  be  difficult  with some language
  249. implementations).   It  returns  the  value  of the second result code
  250. entry in the supplied RexxMsg structure.
  251.  
  252.  
  253. GetToken() - Get the next argument from a string
  254.  
  255. Usage:
  256. Argument = GetToken(String,StartChar,AuxBuff,MaxLength)
  257.    D0                 A0      A1       A2       D0
  258.  
  259. GetToken()  implements easy argument parsing.  ARexx posts commands as
  260. NULL-terminated   strings   with   arguments   separated   by  spaces.
  261. GetToken()  takes  a pointer to the command string (String), a pointer
  262. to  a  counter  variable  (StartChar,  must be a long), a pointer to a
  263. buffer the next argument will be copied to (AuxBuff) and the length of
  264. the  buffer  the  next  argument  will  be copied to (MaxLength).  The
  265. result  will be a pointer to AuxBuff if an argument was found, NULL if
  266. the  end of the command string was reached.  You are to make sure that
  267. the string pointed to by AuxBuff is long enough to hold the arguments.
  268.  
  269.  
  270. GetStringValue() - Return the numeric value of a string
  271.  
  272. Usage:
  273. Value = GetStringValue(String)
  274.   D0                     A0
  275.  
  276. Just  like the 'C' language atoi() function GetStringValue() evaluates
  277. the contents of a string.  Its value is returned as a long word.  This
  278. function  helps  to  analyze  the contents of a RexxMsg result code or
  279. command argument.
  280.  
  281.  
  282. BuildValueString() - Turns a numeric value into a string
  283.  
  284. Usage:
  285. String = BuildValueString(Value,String)
  286.   D0                        D0    A0
  287.  
  288. This  function helps to build a string from a numeric value, just like
  289. the  'C'  language  itoa() function.  The supplied string must be long
  290. enough  to  hold  the digits built from Value.  A pointer to the built
  291. string is returned.
  292.  
  293.  
  294. RexxStrCmp() - Compare two strings ignoring case
  295.  
  296. Usage:
  297. Match = RexxStrCmp(String1,String2)
  298.   D0                 A0      A1
  299.  
  300. This  function  is  intended  to be a replacement for the 'C' function
  301. strcmp().   Other than the builtin strcmp, RexxStrCmp ignores the case
  302. of  both  strings  and even handles international characters correctly
  303. (i.e.   RexxStrCmp("äöüß","ÄÖÜß")  == 0).  The value returned as Match
  304. is  0  if both strings are considered equal, any other value indicates
  305. that both strings are different.
  306.  
  307.  
  308. GetRexxMsg() - Get a RexxMessage from a RexxHost
  309.  
  310. Usage:
  311. RexxMsg = GetRexxMsg(RexxHost,WaitForIt)
  312.    D0                   A0        D0
  313.  
  314. Use  this  function rather than calling GetMsg, since it does RexxHost
  315. type  checking.   As  a  special option, it will wait for a message to
  316. arrive  if  none  is  present  yet.   RexxHost  must  point to a valid
  317. RexxHost  MsgPort structure, WaitForIt must be FALSE (= 0) if you want
  318. this  function  to  return  immediately  if  there are no RexxMessages
  319. pending, TRUE if otherwise.
  320.  
  321.  
  322. SendRexxMsg() - Send a command to a Rexx host
  323.  
  324. Usage:
  325. Result = SendRexxMsg(HostName,MsgList,SingleMsg,GetResult)
  326.   D0                    A0      A1       A2        D0
  327.  
  328. Programs who wish to communicate directly with a Rexx host rather than
  329. posting  lots  of scriptfiles call this function.  HostName must point
  330. to  null  terminated  string  describing  the name of the Rexx host to
  331. receive  the  command,  MsgList  points to an array of null terminated
  332. strings,  SingleMsg points to a null terminated string.  Note:  Either
  333. MsgList  or  SingleMsg  must  be NULL.  The MsgList is copied directly
  334. into the 16 argument vectors of a RexxMsg.  SingleMsg will be put into
  335. argument  vector  zero.  Set GetResult to TRUE if you want a result to
  336. be  returned.   Note  that this function works synchronously and waits
  337. until the reply to the message arrives.
  338.  
  339.  
  340. GetRexxString() - Obtain and deallocate a result string
  341.  
  342. Usage:
  343. GetRexxString(ResultString,DestString)
  344.                    A0          A1
  345.  
  346. The  secondary  result code returned in a RexxMsg can be a string or a
  347. number.  To save system memory the string has to be deallocated.  This
  348. function  performs  two  actions for you:  it copies the result string
  349. into a supplied buffer and deallocates the original string afterwards.
  350. Note:   make sure the result you pass this function is really a string
  351. and  not  a number or you will deallocate innocent memory.  ATTENTION!
  352. There  is a very good chance that non-standard result strings (such as
  353. returned  by CygnusEd Professional 2.xx) cannot be deallocated by this
  354. function.   CEDPro2.xx does not use the standard RexxArg structure for
  355. string  results, but stores the length of the string being returned in
  356. the  first  longword  in front of the first character.  Sometimes this
  357. string is not even null-terminated!
  358.  
  359.  
  360. GetRexxClip() - Find a Rexx clip by name and return one argument
  361.  
  362. Usage:
  363. ArgX = GetRexxClip(Name,WhichArg)
  364.  D0                 A0     D0
  365.  
  366. The  rexx clip list is searched for a rexx resource node.  Returned is
  367. either  Arg1  or  Arg2 depending on the value you pass as WhichArg:  a
  368. value of 0 will return Arg1, 1 returns Arg2.
  369.  
  370. ============================== Nuisance ==============================
  371. ======================================================================
  372. The library could be shorter if the  Aztec 'C' linker  'LN'  generated
  373. proper hunks:
  374.  
  375. 1) DATA  and  BSS hunks are intermixed; as a result the BSS hunk turns
  376.    out to have length zero which will still force DOS to allocate four
  377.    extra bytes which are never used.
  378.  
  379. 2) Additionally  the  DATA/BSS  hunk has to be zeroed 'manually' which
  380.    requires some extra code in crt0.a68.
  381.  
  382. 3) Even  if  you  don't  request a BSS hunk the linker still generates
  383.    one.    The  -  empty  -  hunk  (including  superfluous  relocation
  384.    information) occupies disk space it doesn't need.
  385.  
  386.        Is there any chance this 'kludging' will ever be fixed?
  387.  
  388. ============================== Credits ===============================
  389. ======================================================================
  390. rexxhost.library  was  built  from example source code written by Gary
  391. Samad  &  Bill  Hawes (fancydemo.c), extensions & additional functions
  392. were created by Olaf 'Olsen' Barthel.
  393.    The  entire  contents  of  this library package may be used for any
  394. purpose,  no  regard  whether commercial or non-commercial.  No credit
  395. must  be  given  to  the  creator, nor must a registration fee be paid
  396. (though I wouldn't mind if anybody did).
  397.  
  398.                      THIS IS TRULY PUBLIC DOMAIN!
  399.  
  400. =============================== Author ===============================
  401. ======================================================================
  402.  
  403.                       Olaf 'Olsen' Barthel, MXM
  404.                           Brabeckstrasse 35
  405.                           D-3000 Hannover 71
  406.  
  407.                      Federal Republic of Germany
  408.  
  409.                        Phone: (05 11) 52 23 38
  410.  
  411. ============ Revision history (most recent change first) =============
  412. ======================================================================
  413. 36.14   This  release  fixes  a  potential bug in the GetToken routine
  414.         (Stefan Sticht discovered it).  Tokens may be separated by any
  415.         blank  character  (such as tabs, spaces, newlines, etc.).  The
  416.         Rexx   clip   list  can  be  scanned  using  a  new  function:
  417.         GetRexxClip.   Due  to a bug to be found in the 'C' compiler I
  418.         had  to  remove  the inline library calls and to turn off code
  419.         optimization  in  the  LibMain  module.   Code size climbed by
  420.         about 400 bytes.
  421.  
  422. 35.13   Added    new    functions    (GetRexxMsg,    SendRexxMsg   and
  423.         GetRexxString)   which  I  found  missing  for  the  last  few
  424.         revisions.   I  also  rewrote parts of the library code to get
  425.         rid of those nasty 'goto' statements.
  426.  
  427. 34.12   The  library  can  be recompiled using 16 bit integers now.  I
  428.         don't  know  if  anybody  profits  from  this feature but it's
  429.         included  anyway.   By  the  way:   code  size went up to 2912
  430.         bytes.
  431.  
  432. 34.11   The library  went through  the third major rewrite, along with
  433.         some  more cleanups (nobody told me that the NULL-function has
  434.         to   be  supported)  assembly  language  string-routines  were
  435.         introduced to reduce the amount of support-library code.  Code
  436.         size dropped to 2840 bytes.
  437.  
  438. 34.10   Some  more  cleanups  in  RexxStrCmp  and  other routines were
  439.         really  necessary.   As  a  result,  code size went up to 2900
  440.         bytes.
  441.  
  442. 34.9    Added  more sanity checks in the Rexx Host creation/management
  443.         procedure.  An extended MsgPort structure with additional type
  444.         data  holds  the interface now.  Library code and data are now
  445.         much  more  compact than in the previous releases (I spent two
  446.         additional days debugging the code). Library  size  should  be
  447.         2792 bytes now.
  448.  
  449. 34.8    ANSIfication,   more   cleanups,   added  RexxStrCmp,  rewrote
  450.         CreateRexxHost/DeleteRexxHost  to become shorter, made library
  451.         use #pragma calls rather than  to  rely  on  the  rexxglue.asm
  452.         output file. Code size went down to about 2764 bytes (original
  453.         size: 3512 bytes).
  454.  
  455. 34.7    Ported   to  Aztec  'C'  5.0,  the  strange  library  creation
  456.         procedure  consumed lots of time (in which the author consumed
  457.         lots of cups of coffee).
  458.  
  459. 1.6     Initial creation using MkLib & elib.
  460.